package com.gungnir.trial;

import com.gungnir.trial.entity.ThreeRate;
import com.tyrfing.exceptions.TyrfingServiceException;
import com.tyrfing.model.Pagination;

import java.util.List;

/**
 * Service interface for handling ThreeRate-related operations.
 */
public interface ThreeRateService {

    /**
     * @api {post} /three_rate_service/insert_three_rate 插入ThreeRate记录
     * @apiName insertThreeRate
     * @apiGroup threeRateService
     * @apiDescription 插入一个ThreeRate记录
     * @apiParam {threeRate} threeRate
     * @apiParamExample {json} Request
     * {
     *   "frontRowRate": 0.5,
     *   "attendanceRate": 0.7,
     *   "headUpRate": 0.6,
     *   "classRoomCode": "A101",
     *   "teachingClassCode": "TC123",
     *   "imagShotTime": 1653847405000
     * }
     * @apiSuccessExample {json} Response
     * {
     *   "code": 200,
     *   "msg": "success"
     * }
     */
    void insertThreeRate(ThreeRate threeRate) throws TyrfingServiceException;

    /**
     * @api {post} /three_rate_service/count_and_insert_three_rate 计算并插入ThreeRate记录
     * @apiName countAndInsertThreeRate
     * @apiGroup threeRateService
     * @apiDescription 计算并插入一个ThreeRate记录，根据提供的参数进行计算并保存记录
     * @apiParam {int} sum 总数
     * @apiParam {int} attendanceFaceCount 出席的人脸数
     * @apiParam {int} attendanceCount 出席人数
     * @apiParam {int} frontAttendanceCount 前排出席人数
     * @apiParam {int} clroFrontSeatCount 教室前排座位总数
     * @apiParam {String} classRoomCode 教室编码
     * @apiParam {String} teachingClassCode 教学班号
     * @apiParam {Long} imagShotTime 考勤分析时间
     * @apiParamExample {json} Request
     * {
     *   "sum": 100,
     *   "attendanceFaceCount": 50,
     *   "attendanceCount": 45,
     *   "frontAttendanceCount": 20,
     *   "clroFrontSeatCount": 30,
     *   "classRoomCode": "A101",
     *   "teachingClassCode": "TC123",
     *   "imagShotTime": 1653847405000
     * }
     * @apiSuccessExample {json} Response
     * {
     *   "code": 200,
     *   "msg": "success"
     * }
     */
    void countAndInsertThreeRate(int shouldAttendance, int attendanceFaceCount, int attendanceCount, int frontAttendanceCount, int clroFrontSeatCount, String classRoomCode, String teachingClassCode, Long imagShotTime) throws TyrfingServiceException;

    /**
     * @api {post} /three_rate_service/delete_three_rate 删除ThreeRate记录
     * @apiName deleteThreeRate
     * @apiGroup threeRateService
     * @apiDescription 根据主键(imagShotTime, classRoomCode)删除一个ThreeRate记录
     * @apiParam {Long} imagShotTime
     * @apiParam {String} classRoomCode
     * @apiParamExample {json} Request
     * {
     *   "imagShotTime": 1653847405000,
     *   "classRoomCode": "A101"
     * }
     * @apiSuccessExample {json} Response
     * {
     *   "code": 200,
     *   "msg": "success"
     * }
     */
    void deleteThreeRateByPrimaryKey(Long imagShotTime, String classRoomCode) throws TyrfingServiceException;

    /**
     * @api {post} /three_rate_service/update_three_rate 更新ThreeRate记录
     * @apiName updateThreeRate
     * @apiGroup threeRateService
     * @apiDescription 更新ThreeRate记录通过其主键
     * @apiParam {threeRate} threeRate
     * @apiParamExample {json} Request
     * {
     *   "frontRowRate": 0.5,
     *   "attendanceRate": 0.7,
     *   "headUpRate": 0.6,
     *   "classRoomCode": "A101",
     *   "teachingClassCode": "TC123",
     *   "imagShotTime": 1653847405000
     * }
     * @apiSuccessExample {json} Response
     * {
     *   "code": 200,
     *   "msg": "success"
     * }
     */
    void updateThreeRate(ThreeRate threeRate) throws TyrfingServiceException;

    /**
     * @api {post} /three_rate_service/find_by_time_range 根据时间范围查询ThreeRate记录
     * @apiName findByTimeRange
     * @apiGroup threeRateService
     * @apiDescription 根据时间范围查询ThreeRate记录
     * @apiParam {Integer} pageSize 每页大小
     * @apiParam {Integer} pageNum 页码
     * @apiParam {Long} startTime 开始时间
     * @apiParam {Long} endTime 结束时间
     * @apiParamExample {json} Request
     * {
     *   "startTime": 1653847405000,
     *   "endTime": 1653847406000
     * }
     * @apiSuccessExample {json} Response
     * {
     *     "total": 8,
     *     "pageSize": 3,
     *     "pageNum": 1,
     *     "data": [
     *         {
     *             "id": "66e0efc5544d2b6aa186ccc4",
     *             "insertTime": null,
     *             "updateTime": null,
     *             "deleteTime": null,
     *             "deleted": null,
     *             "frontRowRate": 45.02,
     *             "attendanceRate": 20.0,
     *             "headUpRate": 45.65,
     *             "classRoomCode": "TY856",
     *             "teachingClassCode": "TH856",
     *             "imagShotTime": 1
     *         },
     *         {
     *             "id": "66e0efce544d2b6aa186ccc5",
     *             "insertTime": null,
     *             "updateTime": null,
     *             "deleteTime": null,
     *             "deleted": null,
     *             "frontRowRate": 45.02,
     *             "attendanceRate": 20.0,
     *             "headUpRate": 45.65,
     *             "classRoomCode": "TY856",
     *             "teachingClassCode": "TH856",
     *             "imagShotTime": 2
     *         },
     *         {
     *             "id": "66e0efd1544d2b6aa186ccc6",
     *             "insertTime": null,
     *             "updateTime": null,
     *             "deleteTime": null,
     *             "deleted": null,
     *             "frontRowRate": 45.02,
     *             "attendanceRate": 20.0,
     *             "headUpRate": 45.65,
     *             "classRoomCode": "TY856",
     *             "teachingClassCode": "TH856",
     *             "imagShotTime": 3
     *         }
     *     ],
     *     "header": null
     * }
     */
    Pagination<ThreeRate> findThreeRateByTimeRangePaged(Integer pageSize, Integer pageNum, Long startTime, Long endTime) throws TyrfingServiceException;

    /**
     * @api {post} /three_rate_service/find_by_class_room_code 根据classRoomCode查询ThreeRate记录
     * @apiName findByClassRoomCode
     * @apiGroup threeRateService
     * @apiDescription 根据classRoomCode查询ThreeRate记录数组
     * @apiParam {Integer} pageSize 每页大小
     * @apiParam {Integer} pageNum 页码
     * @apiParam {String} classRoomCode 教室编码
     * @apiParamExample {json} Request
     * {
     *   "classRoomCode": "A101"
     * }
     * @apiSuccessExample {json} Response
     * {
     *     "total": 5,
     *     "pageSize": 1,
     *     "pageNum": 1,
     *     "data": [
     *         {
     *             "id": "66e0efdf544d2b6aa186ccc9",
     *             "insertTime": null,
     *             "updateTime": null,
     *             "deleteTime": null,
     *             "deleted": null,
     *             "frontRowRate": 45.02,
     *             "attendanceRate": 20.0,
     *             "headUpRate": 45.65,
     *             "classRoomCode": "TY857",
     *             "teachingClassCode": "TH857",
     *             "imagShotTime": 6
     *         }
     *     ],
     *     "header": null
     * }
     */
    Pagination<ThreeRate> findThreeRateByClassRoomCodePaged(Integer pageSize, Integer pageNum, String classRoomCode) throws TyrfingServiceException;

    /**
     * @api {post} /three_rate_service/find_by_teaching_class_code 根据teachingClassCode查询ThreeRate记录
     * @apiName findByTeachingClassCode
     * @apiGroup threeRateService
     * @apiDescription 根据teachingClassCode查询ThreeRate记录数组
     * @apiParam {Integer} pageSize 每页大小
     * @apiParam {Integer} pageNum 页码
     * @apiParam {String} teachingClassCode 教学班号
     * @apiParamExample {json} Request
     * {
     *   "teachingClassCode": "TC123"
     * }
     * @apiSuccessExample {json} Response
     * {
     *     "total": 5,
     *     "pageSize": 1,
     *     "pageNum": 1,
     *     "data": [
     *         {
     *             "id": "66e0efdf544d2b6aa186ccc9",
     *             "insertTime": null,
     *             "updateTime": null,
     *             "deleteTime": null,
     *             "deleted": null,
     *             "frontRowRate": 45.02,
     *             "attendanceRate": 20.0,
     *             "headUpRate": 45.65,
     *             "classRoomCode": "TY857",
     *             "teachingClassCode": "TH857",
     *             "imagShotTime": 6
     *         }
     *     ],
     *     "header": null
     * }
     */
    Pagination<ThreeRate> findThreeRateByTeachingClassCodePaged(Integer pageSize, Integer pageNum, String teachingClassCode) throws TyrfingServiceException;

    /**
     * @api {post} /three_rate_service/find_by_time_range_and_class_room_code 根据时间范围和classRoomCode查询ThreeRate记录
     * @apiName findByTimeRangeAndClassRoomCode
     * @apiGroup threeRateService
     * @apiDescription 根据时间范围和classRoomCode查询ThreeRate记录数组
     * @apiParam {Integer} pageSize 每页大小
     * @apiParam {Integer} pageNum 页码
     * @apiParam {Long} startTime 开始时间
     * @apiParam {Long} endTime 结束时间
     * @apiParam {String} classRoomCode 教室编码
     * @apiParamExample {json} Request
     * {
     *   "startTime": 1653847405000,
     *   "endTime": 1653847406000,
     *   "classRoomCode": "A101"
     * }
     * @apiSuccessExample {json} Response
     * {
     *     "total": 5,
     *     "pageSize": 1,
     *     "pageNum": 1,
     *     "data": [
     *         {
     *             "id": "66e0efdf544d2b6aa186ccc9",
     *             "insertTime": null,
     *             "updateTime": null,
     *             "deleteTime": null,
     *             "deleted": null,
     *             "frontRowRate": 45.02,
     *             "attendanceRate": 20.0,
     *             "headUpRate": 45.65,
     *             "classRoomCode": "TY857",
     *             "teachingClassCode": "TH857",
     *             "imagShotTime": 6
     *         }
     *     ],
     *     "header": null
     * }
     */
    Pagination<ThreeRate> findThreeRateByTimeRangeAndClassRoomCodePaged(Integer pageSize, Integer pageNum, Long startTime, Long endTime, String classRoomCode) throws TyrfingServiceException;

    /**
     * @api {post} /three_rate_service/find_by_time_range_and_teaching_class_code 根据时间范围和teachingClassCode查询ThreeRate记录
     * @apiName findByTimeRangeAndTeachingClassCode
     * @apiGroup threeRateService
     * @apiDescription 根据时间范围和teachingClassCode查询ThreeRate记录数组
     * @apiParam {Integer} pageSize 每页大小
     * @apiParam {Integer} pageNum 页码
     * @apiParam {Long} startTime 开始时间
     * @apiParam {Long} endTime 结束时间
     * @apiParam {String} teachingClassCode 教学班号
     * @apiParamExample {json} Request
     * {
     *   "startTime": 1653847405000,
     *   "endTime": 1653847406000,
     *   "teachingClassCode": "TC123"
     * }
     * @apiSuccessExample {json} Response
     * {
     *     "total": 5,
     *     "pageSize": 1,
     *     "pageNum": 1,
     *     "data": [
     *         {
     *             "id": "66e0efdf544d2b6aa186ccc9",
     *             "insertTime": null,
     *             "updateTime": null,
     *             "deleteTime": null,
     *             "deleted": null,
     *             "frontRowRate": 45.02,
     *             "attendanceRate": 20.0,
     *             "headUpRate": 45.65,
     *             "classRoomCode": "TY857",
     *             "teachingClassCode": "TH857",
     *             "imagShotTime": 6
     *         }
     *     ],
     *     "header": null
     * }
     */
    Pagination<ThreeRate> findThreeRateByTimeRangeAndTeachingClassCodePaged(Integer pageSize, Integer pageNum, Long startTime, Long endTime, String teachingClassCode) throws TyrfingServiceException;

    /**
     * @api {post} /three_rate_service/find_latest_by_teaching_class_code_or_class_room_code 查询最新的ThreeRate记录
     * @apiName findLatestByTeachingClassCodeOrClassRoomCode
     * @apiGroup threeRateService
     * @apiDescription 根据teachingClassCode或classRoomCode查询最新的ThreeRate记录
     * @apiParam {Integer} pageSize 每页大小
     * @apiParam {Integer} pageNum 页码
     * @apiParam {String} teachingClassCode 教学班号
     * @apiParam {String} classRoomCode 教室编码
     * @apiParamExample {json} Request
     * {
     *   "teachingClassCode": "TC123",
     *   "classRoomCode": "A101"
     * }
     * @apiSuccessExample {json} Response
     * {
     *     "id": "66e0efed544d2b6aa186cccd",
     *     "insertTime": null,
     *     "updateTime": null,
     *     "deleteTime": null,
     *     "deleted": null,
     *     "frontRowRate": 45.02,
     *     "attendanceRate": 20.0,
     *     "headUpRate": 45.65,
     *     "classRoomCode": "TY857",
     *     "teachingClassCode": "TH857",
     *     "imagShotTime": 10
     * }
     */
    ThreeRate findLatestByTeachingClassCodeOrClassRoomCode(String teachingClassCode, String classRoomCode) throws TyrfingServiceException;
}
